Plugins

Argo CD allows integrating more config management tools using config management plugins.

Configure plugins via Argo CD configmap

Following changes are required to configure new plugin:

  • Make sure required binaries are available in argocd-repo-server pod. The binaries can be added via volume mounts or using custom image (see custom_tools).
  • Register a new plugin in argocd-cm ConfigMap:
  1. data:
  2. configManagementPlugins: |
  3. - name: pluginName
  4. init: # Optional command to initialize application source directory
  5. command: ["sample command"]
  6. args: ["sample args"]
  7. generate: # Command to generate manifests YAML
  8. command: ["sample command"]
  9. args: ["sample args"]
  10. lockRepo: true # Defaults to false. See below.

The generate command must print a valid YAML stream to stdout. Both init and generate commands are executed inside the application source directory.

  • Create an application and specify required config management plugin name.
  1. argocd app create <appName> --config-management-plugin <pluginName>

More config management plugin examples are available in argocd-example-apps.

Repository locking

If your plugin makes use of git (e.g. git crypt), it is advised to set lockRepo to true so that your plugin will have exclusive access to the repository at the time it is executed. Otherwise, two applications synced at the same time may result in a race condition and sync failure.

Configure plugin via sidecar

As an effort to provide first-class support for additional plugin tools, we have enhanced the feature where an operator can configure additional plugin tool via sidecar to repo-server. Following changes are required to configure new plugin:

Register plugin sidecar

To install a plugin, simply patch argocd-repo-server to run config management plugin container as a sidecar, with argocd-cmp-server as it’s entrypoint. You can use either off-the-shelf or custom built plugin image as sidecar image. For example:

  1. containers:
  2. - name: cmp
  3. command: [/var/run/argocd/argocd-cmp-server] # Entrypoint should be Argo CD lightweight CMP server i.e. argocd-cmp-server
  4. image: busybox # This can be off-the-shelf or custom built image
  5. securityContext:
  6. runAsNonRoot: true
  7. runAsUser: 999
  8. volumeMounts:
  9. - mountPath: /var/run/argocd
  10. name: var-files
  11. - mountPath: /home/argocd/cmp-server/plugins
  12. name: plugins
  13. - mountPath: /home/argocd/cmp-server/config/plugin.yaml # Plugin config file can either be volume mapped or baked into image
  14. subPath: plugin.yaml
  15. name: cmp-plugin
  16. - mountPath: /tmp
  17. name: tmp
  18. volumes:
  19. - configMap:
  20. name: cmp-plugin
  21. name: cmp-plugin
  • Make sure to use /var/run/argocd/argocd-cmp-server as an entrypoint. The argocd-cmp-server is a lightweight GRPC service that allows Argo CD to interact with the plugin.
  • Make sure that sidecar container is running as user 999
  • Make sure that plugin configuration file is present at /home/argocd/cmp-server/config/pluging.yaml. It can either be volume mapped via configmap or baked into image

Plugin configuration file

Plugins will be configured via a ConfigManagementPlugin manifest located inside the plugin container, placed at /home/argocd/cmp-server/config/plugin.yaml. Argo CD is agnostic to the mechanism of how the configuration file would be placed, but various options can be used on how to place this file, including:

  • Baking the file into the plugin image as part of docker build.
  • Volume mapping the file through a configmap.
  1. apiVersion: argoproj.io/v1alpha1
  2. kind: ConfigManagementPlugin
  3. metadata:
  4. name: cmp-plugin
  5. spec:
  6. version: v1.0
  7. generate:
  8. command: [sh, -c, 'echo "{\"kind\": \"ConfigMap\", \"apiVersion\": \"v1\", \"metadata\": { \"name\": \"$ARGOCD_APP_NAME\", \"namespace\": \"$ARGOCD_APP_NAMESPACE\", \"annotations\": {\"Foo\": \"$FOO\", \"KubeVersion\": \"$KUBE_VERSION\", \"KubeApiVersion\": \"$KUBE_API_VERSIONS\",\"Bar\": \"baz\"}}}"']
  9. discover:
  10. fileName: "./subdir/s*.yaml"
  11. allowConcurrency: true
  12. lockRepo: false

Note that, while the ConfigManagementPlugin looks like a Kubernetes object, it is not actually a custom resource. It only follows kubernetes-style spec conventions.

The generate command must print a valid YAML stream to stdout. Both init and generate commands are executed inside the application source directory.

The discover.fileName is used as matching pattern to determine whether application repository is supported by the plugin or not.

  1. discover:
  2. find:
  3. command: [sh, -c, find . -name env.yaml]

If discover.fileName is not provided, the discover.find.command is executed in order to determine whether application repository is supported by the plugin or not. The find command should returns non-error response in case when application source type is supported.

If your plugin makes use of git (e.g. git crypt), it is advised to set lockRepo to true so that your plugin will have exclusive access to the repository at the time it is executed. Otherwise, two applications synced at the same time may result in a race condition and sync failure.

Volume map plugin configuration file via configmap

The plugin.yaml file can be delivered using a configmap. Create a Kubernetes config map and with the plugin.yaml key that holds the plugin configuration file:

  1. apiVersion: v1
  2. kind: ConfigMap
  3. metadata:
  4. name: cmp-plugin
  5. data:
  6. plugin.yaml: |
  7. apiVersion: argoproj.io/v1alpha1
  8. kind: ConfigManagementPlugin
  9. metadata:
  10. name: cmp-plugin
  11. spec:
  12. version: v1.0
  13. generate:
  14. command: [sh, -c, 'echo "{\"kind\": \"ConfigMap\", \"apiVersion\": \"v1\", \"metadata\": { \"name\": \"$ARGOCD_APP_NAME\", \"namespace\": \"$ARGOCD_APP_NAMESPACE\", \"annotations\": {\"Foo\": \"$FOO\", \"KubeVersion\": \"$KUBE_VERSION\", \"KubeApiVersion\": \"$KUBE_API_VERSIONS\",\"Bar\": \"baz\"}}}"']
  15. discover:
  16. fileName: "./subdir/s*.yaml"
  17. allowConcurrency: true
  18. lockRepo: false

Environment

Commands have access to

  1. The system environment variables
  2. Standard build environment
  3. Variables in the application spec (References to system and build variables will get interpolated in the variables’ values):

v1.2

  1. spec:
  2. source:
  3. plugin:
  4. env:
  5. - name: FOO
  6. value: bar
  7. - name: REV
  8. value: test-$ARGOCD_APP_REVISION